home *** CD-ROM | disk | FTP | other *** search
/ Aminet 30 / Aminet 30 (1999)(Schatztruhe)[!][Apr 1999].iso / Aminet / util / libs / ppclibemu.lha / README < prev    next >
Text File  |  1999-01-24  |  11KB  |  331 lines
  1.  
  2. ---------- ppclibemu V0.5  - The ppc.library emulation for WarpOS ----------
  3.  
  4.  
  5. INTRODUCTION
  6.     The PowerPC-Amiga seems to move in the direction of WarpOS, as
  7.     more and more programs are WarpOS-only.
  8.     Most prominent: StormMesa (OpenGL), Warp3D, M68k-Emulator, OS3.5(?).
  9.  
  10.     Some may like it and some not. I like features in both kernels,
  11.     and in my opinion there must be a possibility to run most of the old
  12.     PowerUp software under WarpOS in future. I'm also sick of rebooting
  13.     my system, when switching the kernel. So the only solution is:
  14.     ppc.library emulation under WarpOS!
  15.  
  16.  
  17. FEATURES
  18.     Since V0.5 you can start ELF objects directly (from shell or
  19.     from Workbench). The emulation library installs a LoadSeg()-patch
  20.     which detects and starts ELF objects. But in opposition to the
  21.     original library, the patch can be removed when the library is
  22.     expunged ("avail flush"). ;)
  23.  
  24.     Of course you can also start ELF objects by using SAS/C's RunElf,
  25.     Ralph Schmidt's PPCLoad or vbcc's PPCRun V1.0 (PPCRun V0.9a and
  26.     older don't work, because they use the PowerUp message system).
  27.  
  28.     Most important parts of the ppc.library which are still missing:
  29.       o PowerUp message system (startup messages, etc.)
  30.       o Asynchronous PowerPC tasks
  31.       o Asymchronous M68k calls
  32.       o Exception handling, debugger support
  33.       o Semaphores
  34.       o Cache functions
  35.       o Loading an ELF object from a PowerPC task
  36.       o Pooled memory has to be simulated (until powerpc.library V15 is out)
  37.     Especially mixed binary programs (and many others :) will not work.
  38.  
  39.     The following functions of the original ppc.library are supported:
  40.       o PPCLoadObject
  41.       o PPCUnLoadObject
  42.       o PPCRunObject
  43.       o PPCAllocMem (MEMF_NOCACHESYNCxxx not supported)
  44.       o PPCFreeMem
  45.       o PPCAllocVec (MEMF_NOCACHESYNCxxx not supported)
  46.       o PPCFreeVec
  47.       o PPCDebugMode (private, doesn't work like the original)
  48.       o PPCCreateTask (only synchronous tasks)
  49.       o PPCGetAttrs (PPCINFOTAG_EXCEPTIONHOOK not supported)
  50.       o PPCReadLong
  51.       o PPCWriteLong
  52.       o PPCGetObjectAttrs
  53.       o PPCWriteLongFlush
  54.       o PPCReadWord
  55.       o PPCWriteWord
  56.       o PPCReadByte
  57.       o PPCWriteByte
  58.       o PPCCacheClearE
  59.       o PPCLoadObjectTagList
  60.  
  61.     The following functions of the original PowerUp kernel are supported:
  62.       o PPCAdd64
  63.       o PPCAdd64p
  64.       o PPCAddHead
  65.       o PPCAddHeadSync (implementation may be incorrect)
  66.       o PPCAddTail
  67.       o PPCAddTailSync (implementation may be incorrect)
  68.       o PPCAllocMem (NOCACHESYNCM68K simulated by allocating chip RAM)
  69.       o PPCAllocPooled (No pooled mem under WOS, same as PPCAllocMem)
  70.       o PPCAllocSignal
  71.       o PPCAllocVec (NOCACHESYNCM68K simulated by allocating chip RAM)
  72.       o PPCAllocVecPooled (No pooled mem under WOS, same as PPCAllocVec)
  73.       o PPCAnd64
  74.       o PPCAnd64p
  75.       o PPCAsl64
  76.       o PPCAsl64p
  77.       o PPCAsr64
  78.       o PPCAsr64p
  79.       o PPCCallM68k (Flags ignored. Asynchronous calls are synchronous.)
  80.       o PPCCallOS (Flags ignored. Asynchronous calls are synchronous.)
  81.       o PPCClose
  82.       o PPCCloseLibrary
  83.       o PPCCmp64
  84.       o PPCCmp64p
  85.       o PPCCreatePool (No pooled mem under WOS, returns dummy)
  86.       o PPCCreateTimerObject
  87.       o PPCDeletePool (Dummy. No pooled mem under WOS)
  88.       o PPCDeleteTimerObject
  89.       o PPCDivRem64
  90.       o PPCDivRem64p
  91.       o PPCDivs64
  92.       o PPCDivs64p
  93.       o PPCDivu64
  94.       o PPCDivu64p
  95.       o PPCEnqueue
  96.       o PPCEnqueueSync (implementation may be incorrect)
  97.       o PPCFindTagItem
  98.       o PPCFindTask
  99.       o PPCFinishTask
  100.       o PPCFreeMem
  101.       o PPCFreePooled (No pooled mem under WOS, same as PPCFreeMem)
  102.       o PPCFreeSignal
  103.       o PPCFreeVec
  104.       o PPCFreeVecPooled (No pooled mem under WOS, same as PPCFreeVec)
  105.       o PPCGetAttr
  106.       o PPCGetLibSymbol
  107.       o PPCGetTagData
  108.       o PPCGetTaskAttr (PPCTASKTAG_STACKSIZE only)
  109.       o PPCGetTimerObject
  110.       o PPCInput
  111.       o PPCInsert
  112.       o PPCInsertSync (implementation may be incorrect)
  113.       o PPCLsl64
  114.       o PPCLsl64p
  115.       o PPCLsr64
  116.       o PPCLsr64p
  117.       o PPCMods64
  118.       o PPCMods64p
  119.       o PPCModu64
  120.       o PPCModu64p
  121.       o PPCMuls64
  122.       o PPCMuls64p
  123.       o PPCMulu64
  124.       o PPCMulu64p
  125.       o PPCNeg64
  126.       o PPCNeg64p
  127.       o PPCNewList
  128.       o PPCNextTagItem
  129.       o PPCOpen
  130.       o PPCOpenLibrary
  131.       o PPCOr64
  132.       o PPCOr64p
  133.       o PPCOutput
  134.       o PPCRead
  135.       o PPCRemHead
  136.       o PPCRemHeadSync (implementation may be incorrect)
  137.       o PPCRemove
  138.       o PPCRemoveSync (implementation may be incorrect)
  139.       o PPCRemTail
  140.       o PPCRemTailSync (implementation may be incorrect)
  141.       o PPCRevision
  142.       o PPCSeek
  143.       o PPCSetSignal
  144.       o PPCSetTimerObject
  145.       o PPCSignal (might not work, because of different task definitions)
  146.       o PPCSub64
  147.       o PPCSub64p
  148.       o PPCVersion
  149.       o PPCWait
  150.       o PPCWrite
  151.       o PPCXor64
  152.       o PPCXor64p
  153.       o memcpy
  154.       o strcmp
  155.       o strcpy
  156.       o strlen
  157.       o __adddi3
  158.       o __anddi3
  159.       o __ashldi3
  160.       o __ashrdi3
  161.       o __cmpdi2
  162.       o __divdi3
  163.       o __fixdfdi
  164.       o __fixsfdi
  165.       o __fixunsdfdi
  166.       o __fixunssfdi
  167.       o __floatdidf
  168.       o __floatdisf
  169.       o __floatunsdidf
  170.       o __iordi3
  171.       o __lmulq
  172.       o __lshldi3
  173.       o __lshrdi3
  174.       o __moddi3
  175.       o __muldi3
  176.       o __negdi2
  177.       o __qdivrem
  178.       o __subdi3
  179.       o __ucmpdi2
  180.       o __udivdi3
  181.       o __umoddi3
  182.       o __xordi3
  183.  
  184.     Unimplemented M68k functions will return with d0=0 and PPC
  185.     functions return with r3=0.
  186.  
  187.  
  188. REQUIREMENTS
  189.     o 68040 or 68060
  190.     o CyberstormPPC or BlizzardPPC
  191.     o WarpOS with powerpc.library V14+ (note that ppclibemu will
  192.       require V15 in future)
  193.  
  194.  
  195. BLIZZARD PPC NOTES
  196.     You will get some problems on a BPPC with a new flash ROM, because
  197.     the original ppc.library is a resident module and will be
  198.     initialized during reset.
  199.  
  200.     The only chance is to use BPPCFix and install another resident
  201.     module, which removes the ppc.library from the system before
  202.     it can initialize itself. Refer to INSTALLATION for further
  203.     informations.
  204.  
  205.     Afterwards you have a 'clean' system, which allows you to start
  206.     WarpOS without using a Terminator (as on a CSPPC). Please
  207.     change the Terminator setting from '2' to '1' or '0'. WarpOS will
  208.     not work with the emulation in terminator-mode '2'.
  209.  
  210.  
  211. INSTALLATION
  212.     Save your original ppc.library:
  213.  
  214.       > copy libs:ppc.library libs:ppc.library.orig
  215.  
  216.     Copy the ppc.library emulation from this directory to libs:
  217.  
  218.       > copy ppc.library libs:
  219.  
  220.     The powerpc.library has to be patched. Otherwise it will prevent
  221.     the ppc.library from opening (powerpc.library V15 will offer a
  222.     new termination mode for this purpose). The patch was tested with
  223.     powerpc.library 14.6 (16.07.98), but it should work for other
  224.     versions too:
  225.  
  226.       > repl libs:powerpc.library "ppc.library\0warp" "xxx.library\0warp"
  227.       libs:powerpc.library: Replacement at 0x16820
  228.       1 replacement(s) in libs:powerpc.library.
  229.  
  230.     Optionally, all these steps can be done automatically, by executing
  231.     the INSTALL script:
  232.       > execute INSTALL
  233.  
  234.     Blizzard PPC owners only:
  235.       Disable the original ppc.library resident module with
  236.         > BPPCFix install
  237.  
  238.       If you want to disable the original library for a longer
  239.       time, you may also put the BPPCFix into your S:Startup-Sequence:
  240.         ; $VER: Startup-Sequence_HardDrive 40.2 (25.2.93)
  241.         ; Startup-Sequence for hard drive systems
  242.         BPPCFix install reboot
  243.         [...]
  244.  
  245.       If the fix is not already installed, it will do so and
  246.       automatically reboot the system.
  247.  
  248.     Finally reboot your system to flush the old ppc.library and/or load
  249.     the patched powerpc.library.
  250.  
  251.  
  252. USAGE
  253.     For a check, you might want to try the supplied test ELF object,
  254.     which was compiled by vbcc-ppc:
  255.  
  256.       > hello_world.elf
  257.       Hello World!
  258.  
  259.     or:
  260.       > runelf hello_world.elf
  261.       Hello World!
  262.  
  263.     The other program in "tests/" is objattr_demo, a 68k program for
  264.     testing the PPCGetObjectAttrs() function. For example, you can
  265.     try to list all symbols of hello_world.elf:
  266.  
  267.       > objattr_demo hello_world.elf
  268.       0x00000000      0x00000000
  269.       0x00000000      0x00000000
  270.       0x00000000      0x00000000
  271.       0x00000000      0x00000000
  272.       0x00000000      0x00000000
  273.       0x00000110      0x00000000      __error
  274.       0x000001F8      0x00000100      parse_cli_args
  275.       [...]
  276.  
  277.  
  278. COMPATIBILITY
  279.     There's absolutely no problem with ELF objects generated by
  280.     vbcc-ppc, provided they don't use unsupported features like
  281.     PowerUp messaging.
  282.  
  283.     I enhanced the ELF-loader in V0.4c to support common symbols.
  284.     gcc or egcs (or both?) uses them since some time, which caused
  285.     strange crashes. This was a major reason for many crashes of
  286.     earlier ppclibemu-versions by the way. Aligned memory for common
  287.     symbols is allocated in the .bss section. If no .bss section is
  288.     present, a new one will be created.
  289.  
  290.     I don't have the time for testing numerous PowerUp programs,
  291.     but the following should work:
  292.       o ADoomPPC (when started by runelf, use "setenv DOOMWADDIR")
  293.       o VDoom (PPCLoad only - old startup code doesn't support runelf)
  294.       o Some demos: VAEDies and VAGhost
  295.       o musicin, musicout
  296.       o Packers: unlzx, lha, unrar, uuencode, uudecode, etc.
  297.       o Emulators: PPCFrodo, AmigaVGBPPC
  298.       o qmap
  299.       o SManPPC
  300.       o Benoit V2.0
  301.  
  302.  
  303. BUGS
  304.     Most functions of ppc.library and many of the PowerUp kernel are
  305.     simply not supported, so I'm not interested in bug reports saying:
  306.     "xyz crashes, maybe it calls an unsupported function...".
  307.  
  308.     If you get any difficulties (I'm sure you will :), then try to
  309.     isolate the problem by enabling the debugging mode. You can
  310.     enable debugging mode on the 68k-side by using the ppcdbmode
  311.     utility:
  312.       ppcdbmode 1      - enables all error requesters
  313.       ppcdbmode 0x8000 - enables serial debugging (you can use Sushi)
  314.     (or ppcdbmode 0x8001 to enable both).
  315.     You can get full serial debugging (kernel emulation too) by
  316.     exchanging ppc.library with ppc.library.debug.
  317.  
  318.     If you think that you found a bug, then send me the last lines of
  319.     this serial debugging output, give me the name of the program and
  320.     the arguments. You should be able to determine by yourself, if it's
  321.     a real bug or only an unimplemented function which causes the problems.
  322.  
  323.     For example I had crashes with AMP (MPEG movie player), because
  324.     it calls PPCGetTaskAttr() with the unsupported EXTUSERDATA tag
  325.     (a ixemul-only tag, if I understand correctly). Maybe somebody
  326.     could explain me the meaning? :)
  327.  
  328.  
  329.  
  330. Frank Wille                  24-Jan-1999                frank@phoenix.owl.de
  331.